Neither the whole nor any part of this manual, or the software described herein may be adapted or reproduced in any material form except with the prior written approval of the author.
The software described in this manual is subject to continuous development and improvement. All information of a technical nature and particulars of the software and its use (including the information and particulars in this manual) are given by Kasoft Software in good faith. However, Kasoft Software will not accept liability for any loss or damage arising from the use of the software or the documentation in this manual.
Suggestions for future versions of the software and this manual are welcomed. All correspondence should be addressed to:
Kade Hansson
Kasoft Software
4/73 Alexander Street
Shearwater 7307
AUSTRALIA
Telephone (International): [61] 3 64287448
Telephone (Australia): (03) 64287448
e-mail: kade_fh@postoffice.utas.edu.au
The relocatable module 'KaData' was programmed by Kade Hansson. This module is suitable for use with all ARM-based computers running Acorn RISC OS version 2.00 or later. This extract is from the third issue of the prepress edition of this manual. It documents version 0.51 (08 Dec 1997).
This extract or the software it documents has no connection with Acorn Computers Limited, but necessary registration of the module title and allocation of a software interrupt chunk number has been carried out. Thus, the software should not interfere with other software which has taken similar precautions.
KASOFT is a trademark of Kasoft Software, and owned by Kade Hansson.
ACORN is a trademark of Acorn Computers Limited.
Prepress Edition (ASCII text file version)
Published May 1998; Issue 5
Written by Kade Hansson
Printed version published by Kasoft Typesetting
Code KM09601,00E
_____________________
KaData Support Module
_____________________
The KaData support module was initially developed by Kasoft to provide a comprehensive programmer's toolkit for use with the KaData Database Management System. It will eventually implement utility operations for the Obmat file format, which is (or will be) used by FiletypeExtend, FileWrapHandler, FileBox, KaData, and the KaProdesy Program Definition System.
The module provides many general-purpose utility routines for maipulating blocks of data in memory, including:
- block copy
- block fill
- byte search (including a routine to traverse delimited data)
- word search
- string search (including provision for simple case insensitivity)
- wildcarded search (providing for proper accent and case insenstivity)
Some of the simple search routines (for bytes, words and strings) were written with optimum performance on the ARM2 architecture in mind, with mild employment of "loop unrolling" increasing code length by up to a factor of 4. In future, these may be supplemented by specialized routines which are automatically substituted according to the capabilities of the processor in use. The software is believed to be StrongARM compatible, although we have no capability to test software with this processor yet.
Also included in the module are utility functions for more specific purposes. These include functions to:
- assemble an ARM instruction from specified parameters
(useful in a compiler back-end*),
- perform efficient searches in a variety of data structures,
- aid in the construction of filing systems & Filer-like applications
(with routines for wildcarded matching, leafname validation etc.),
- access the KaData general-purpose module format
(for generating RISC OS menus among other things),
- maintain multiple shifting heaps
(with full control over each allocated block),
- read and write arbitrarily terminated strings to files, and
- control a timer based on IOC Timer 1.
* This routine was used in the KaModula2Library module, but that module (which was never released) has been renamed to KaProdesy, and all KaModula2 SWI definitions have been revoked in order that a new set may be placed in that chunk (&48300, Acorn registered).
In combination with our AddressDevice DA product, in-house versions of the KaData module provide support for the full 32-bit address space possible on newer ARM architectures. However the relevant entry points are currently disabled, due to the lack of testing done. The special entry points allow ARM6 and later architectures to run routines in the full 32-bit address space. Previously, this had not been possible under RISC OS, as it uses 26-bit PC ARM processor modes for backwards compatibility.
The advantages of using 32-bit address space are significant. Specially designed modules can be placed in dynamic areas, eliminating the need for a fragmented relocatable module area. Also, it is possible to implement virtual memory for programs running in 32-bit space.
This module was written by Kasoft Software and it is subject to continuous development and improvement. Updates to new versions and licences for distributing this module with commercial software are available. Feel free to contact us at the address given on the release note. Criticisms and suggestions for improvement will be appreciated. Please note that copyright subsists in this software and it may not be freely distributed unless written permission has been given by us.*
* Excepting versions up to 0.99, which are public domain releases with possibly limited functionality.
_________________
Technical Details
_________________
Errors
The errors generated by the KaData support module are described here. The SWI chunk number (&482C0) should be added to the error numbers given here to get the full error number.
SWI not implemented
KaData support error number 0. This error indicates that the SWI called has no entry point defined in the instantiated version of the module.
Obmat file header is corrupted
KaData support error number 1. This error usually indicates that an Obmat file's header has become corrupted. Also generated by other Obmat-aware software which is not able to read multi-chunk, big endian, or non-base 32 Obmats, in which case the error message may vary. If this error is generated by KaData_ObmatOp 0 (verify file integrity), then you can be sure that the header is actually corrupted.
Obmat file is corrupted: missing expected marker
KaData support error number 2. This error usually indicates that an Obmat file has become corrupted, as it does not have a marker where one is expected. Also generated by other Obmat-aware software which is confused by an Obmat structure more complex than it can deal with. If this error is generated by KaData_ObmatOp 0 (verify file integrity), then you can be sure that the file is actually corrupted.
Cannot search for null string
KaData support error number 3. This error occurs when an attempt is made to search a block of memory for a null string.
Cannot enter module: outside 26-bit space
KaData support error number 4. An attempt has been made to start executing a module in 32-bit space. This cannot be reasonably implemented at this time.
TabModule cannot initialize: nil actual module pointer
KaData support error number 6. An attempt has been made to initialize a malformed TabModule. The address of the actual module has not been specified as required.
Bad KaData_SpecificSearch reason code
KaData support error number 7. This error arises when an invalid reason code is passed to KaData_SpecificSearch (SWI &482C7). Valid reason codes currently lie in the range 0-1.
Bad KaData_Filer reason code
KaData support error number 8. This error arises when an invalid reason code is passed to KaData_Filer (SWI &482C8). Valid reason codes currently lie in the range 0-2.
KaData is in use
KaData support error number 13. This error occurs when an attempt is made to kill or reinitialize the KaData module after its address in the RMA address space has been anchored by one or more calls to KaData_GetEntryPoints -3 (SWI &482CD). The module cannot successfully finalize until it has been released with a matching number of calls to KaData_GetEntryPoints -4. The current number of users of the support module is recorded in the system variable KaData$ModuleAnchor. The module will die if this variable is unset, but this should be taken as a last resort only, as programs may still be calling the entry points.
Required Territory character table not found
KaData support error number 24. This error occurs when the TerritoryManager module fails to return a character table for the configured territory. A common cause is that the TerritoryManager module is not present (e.g. in RISC OS 2).
Bad KaData_Module reason code
KaData support error number 27. This error arises when an invalid reason code is passed to KaData_Module (SWI &482DB). Valid reason codes currently lie in the range 0-1.
Invalid address: translation to offset failed
KaData support error number 62. This error occurs when an attempt is made to assemble an instruction with an address that cannot be successfully embedded in an ARM instruction as a PC-relative offset.
Invalid immediate constant
KaData support error number 63. This error occurs when an attempt is made to assemble an instruction with an immediate constant that cannot be successfully embedded in an ARM instruction.
_________
SWI Calls
_________
Index to KaData SWIs
Number Name
482C0 KaData_MoveBytes
482C1 KaData_SearchByte
482C2 KaData_SearchWord
482C3 KaData_SearchString
482C4 KaData_SearchAlpha
482C5 KaData_SearchWildString
482C6 KaData_SearchWildAlpha
482C7 KaData_SpecificSearch
482C8 KaData_Filer
482C9 KaData_FillBytes
482CA KaData_ReadInteger
482CB KaData_WriteInteger
482CC KaData_CountBytes
482CD KaData_GetEntryPoints
482CE KaData_CallSupervisor32
482CF KaData_ChangeHardwareVector32
482D0 KaData_OSModule
482D1 KaData_Assemble
482D2 KaData_MetronomicTimerOn
482D3 KaData_MetronomicTimerOff
482D4 KaData_MetronomicTimerSmash
482D5 KaData_ReadMetronomicTimer
482D6 KaData_PokeDynamicArea
482D7 KaData_ObmatOp
482D8 KaData_MatchWild
482D9 KaData_CopyString
482DA KaData_Heap
482DB KaData_Module
482DC KaData_GetString
482DD KaData_PutString
482DE KaData_SetMetronomicTimerQuantum
KaData_MoveBytes
(SWI &482C0)
Copy a block of memory to a new address
On entry
R1 = source address
R2 = destination address
R3 = length
On exit
R0-R3 corrupted
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast memory copy routine, modelled on the one given by Acorn in the chapter on Filing Systems in the Programmers Reference Manual (RISC OS 2, p. 1000). It copies any number of bytes (>0) from the source address to the destination address.
Related SWIs
KaData_FillBytes (SWI &482C9)
Related vectors
None
KaData_SearchByte
(SWI &482C1)
Search for a given byte in a block of memory
On entry
R0 = byte to search for
R1 = start address
R2 = block for list of matching addresses
R3 = length of block to be searched
R4 = maximum size of matching address list (R4 < 4 means no list)
On exit
R0 preserved
R1 = address of byte where search would resume
R2 = block of matching addresses
R3 = number of bytes left to be searched (0 means search complete)
R4 preserved
R5 = number of matches before address in R1 (0 means not found)
R6 = address of last match (if R5 > 0, else preserved)
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast byte search routine. In simple use, without a buffer, it can find the first instance of a byte in a designated block of memory.
If a matching address list block is specified, on exit it is updated with addresses of matching bytes. If the buffer was filled before the search could be completed, the call can be repeated to obtain subsequent lists of matches.
N.B. If the matching address list was filled up, R6 contains the match which would not fit in the list. The number of matches (returned in R5) includes this one.
Search for a given 32-bit word in a block of memory
On entry
R0 = word to search for
R1 = start address (word aligned)
R2 = block for list of matching addresses
R3 = length of block to be searched (multiple of 4)
R4 = maximum size of matching address list (R4 < 4 means no list)
On exit
R0 preserved
R1 = address of word where search would resume
R2 = block of matching addresses
R3 = number of bytes left to be searched (0 means search complete)
R4 preserved
R5 = number of matches before address in R1 (0 means not found)
R6 = address of last match (if R5 > 0, else preserved)
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast 32-bit word search routine. In simple use, without a buffer, it can find the first instance of a word in a designated block of memory.
If a matching address list block is specified, on exit it is updated with addresses of matching words. If the buffer was filled before the search could be completed, the call can be repeated to obtain subsequent lists of matches.
N.B. If the matching address list was filled up, R6 contains the match which would not fit in the list. The number of matches (returned in R5) includes this one.
Related SWIs
KaData_SearchByte (SWI &482C1)
Related vectors
None
KaData_SearchString
(SWI &482C3)
Search for a string of bytes in a block of memory (case sensitive)
On entry
R0 = pointer to search string (null terminated)
R1 = start address
R2 = block for list of matching addresses
R3 = length of block to be searched
R4 = maximum size of matching address list (R4 < 4 means no list)
On exit
R0 preserved
R1 = address of byte where search would resume
R2 = block of matching addresses
R3 = number of bytes left to be searched (0 means search complete)
R4 preserved
R5 = number of matches before address in R1 (0 means not found)
R6 = address of last character which matched the first in search string
(if R5 > 0, else preserved)
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast string search routine. In simple use, without a buffer, it can find the first instance of a string in a designated block of memory.
If a matching address list block is specified, on exit it is updated with addresses of matching strings. If the buffer was filled before the search could be completed, the call can be repeated to obtain subsequent lists of matches.
N.B. If the matching address list was filled up, R6 contains the match which would not fit in the list. The number of matches (returned in R5) includes this one.
Search for a string of bytes in a block of memory (case insensitive)
On entry
R0 = pointer to search string (null terminated)
R1 = start address
R2 = block for list of matching addresses
R3 = length of block to be searched
R4 = maximum size of matching address list (R4 < 4 means no list)
On exit
R0 preserved
R1 = address of byte where search would resume
R2 = block of matching addresses
R3 = number of bytes left to be searched (0 means search complete)
R4 preserved
R5 = number of matches before address in R1 (0 means not found)
R6 = address of last character which matched the first in search string
(if R5 > 0, else preserved)
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast string search routine where the byte comparisons are insensitive to case for characters in the ASCII range 32-127. In simple use, without a buffer, it can find the first instance of a string in a designated block of memory.
If a matching address list block is specified, on exit it is updated with addresses of matching strings. If the buffer was filled before the search could be completed, the call can be repeated to obtain subsequent lists of matches.
N.B. If the matching address list was filled up, R6 contains the match which would not fit in the list. The number of matches (returned in R5) includes this one.
Search for a wildcarded string of characters in a block of memory
(case sensitive)
On entry
R0 = pointer to wildcarded search string
R1 = start address
R2 = block for list of matching addresses
R3 = length of block to be searched
R4 = maximum size of matching address list (R4 < 4 means no list)
R5 = single (one) character wildcard
R6 = multiple (zero or more) character wildcard
R7 = multiple wildcard exclusion character
On exit
R0 preserved
R1 = address of byte where search would resume
R2 preserved
R3 = number of bytes left to be searched (0 means search complete)
R4 preserved
R5 = number of matches before address in R1 (0 means not found)
R6 = address of last match (if R5 > 0, else corrupted)
R7 preserved
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast wildcarded string search routine. In simple use, without a buffer, it can find the first instance of a wildcarded string in a designated block of memory.
The wildcard characters used need to be specified, and a character which cannot form a part of a string matching the multiple wildcard should also be given. The exclusion character defines this routine to be a search through delimited character data, where the exclusion character is part of the delimiter.
If a matching address list block is specified, on exit it is updated with addresses of matching strings. If the buffer was filled before the search could be completed, the call can be repeated to obtain subsequent lists of matches.
N.B. If the matching address list was filled up, R6 contains the match which would not fit in the list. The number of matches (returned in R5) includes this one.
Search for a wildcarded string of characters in a block of memory
(case insensitive)
On entry
R0 = pointer to wildcarded search string
R1 = start address
R2 = block for list of matching addresses
R3 = length of block to be searched
R4 = maximum size of matching address list (R4 < 4 means no list)
R5 = single (one) character wildcard
R6 = multiple (zero or more) character wildcard
R7 = multiple wildcard exclusion character
On exit
R0 preserved
R1 = address of byte where search would resume
R2 preserved
R3 = number of bytes left to be searched (0 means search complete)
R4 preserved
R5 = number of matches before address in R1 (0 means not found)
R6 = address of last match (if R5 > 0, else corrupted)
R7 preserved
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast wildcarded string search routine where the character comparisons are insensitive to case as defined by the current territory. In simple use, without a buffer, it can find the first instance of a wildcarded string in a designated block of memory.
The wildcard characters used need to be specified, and a character which cannot form a part of a string matching the multiple wildcard should also be given. The exclusion character defines this routine to be a search through delimited character data, where the exclusion character is part of the delimiter.
If a matching address list block is specified, on exit it is updated with addresses of matching strings. If the buffer was filled before the search could be completed, the call can be repeated to obtain subsequent lists of matches.
N.B. If the matching address list was filled up, R6 contains the match which would not fit in the list. The number of matches (returned in R5) includes this one.
This routine requires the lower case character translation table provided via the TerritoryManager module, which should be installed prior to calling this routine. If you are using RISC OS 2, you will need to build your own wildcarded search around KaData_SearchAlpha (SWI &48C24), as this does not use a table.
R1 = address base (0 if pointers are absolute addresses)
R2 = pointer to table of pointers
R3 = number of pointers in table
R4 = map to find each object's name
R5 = pointer to object name to seek (null terminated)
On exit
R0,R1 preserved
R2 = if R0=0 on entry, pointer to table entry of first matching object (or -1 if none matched)
R2 = if R0=1 on entry, pointer to table entry of matching object (or insertion point if none matched)
R3 = if R0=0 on entry, number of pointers unchecked
R3 = if R0=1 on entry, 0 if none matched, else non-zero
R4,R5 preserved
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This routine is used by KaData and AddressDevice DA to find an object given its name. In KaData, it picks a subobject out of a collection object, and in AddressDevice DA, it picks an object out of a directory.
R4 gives the routine directions on how to find the object name from each pointer, as follows:
Bits Meaning
0-7 Offset to name in each object (or adjustment to add to name offset)
8-15 Offset to name offset in each object (1 if no name offset used)
16-30 Reserved (must be 0)
31 Set to indicate that pointers in table indirect through anchors
If R0 = 0 on entry, the object name pointed to by R5 may contain the following wildcard characters:
# Matches any character
* Matches a sequence of characters of any length from 0 upwards
The character "." is considered to be an alternative terminator, to complete the similarity of the matching scheme with filing systems.
The search is performed with case insensitive comparisons using KaData_MatchWild (SWI &482D8). This requires the lower case character translation table provided via the TerritoryManager module, which should be installed prior to calling this routine.
The routine may be called multiple times to obtain each matching object. Note that R2 should be advanced by one word (4 bytes) so that it points to the object after the one which matched. R3 is already set-up with the correct value to proceed with the search.
If R0 = 1 on entry, a binary search is employed, which assumes that the table of pointers is sorted in ascending order of object name. Territory_Collate (SWI &4305D) is used to compare (case insensitively) each object name against the one which is being looked for, so this reason code is only valid if the TerritoryManager module is installed. Wildcards cannot be used, and the terminator must be a null.
KaData_Filer
(SWI &482C8)
Provides support calls for a Filer-like application
On entry
R0 = reason code
other registers are parameters and depend upon the reason code
On exit
registers depend on the reason code
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This SWI provides a number of calls for Filer-like applications.
R0 Action
0 Check leafname for wildcards
1 Validate non-wildcarded leafname
2 Find next element of pathname
Related SWIs
None
Related vectors
None
KaData_Filer 0
(SWI &482C8)
Checks whether an object leafname contains wildcards
On entry
R0 = 0
R1 = pointer to object leafname (null or period terminated)
On exit
R0,R1 preserved
Z set if object leafname does not contain wildcards
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This routine is used by AddressDevice DA to determine if a binary search can be used to resolve pathname elements. It could be used in a similar way by other filing systems.
KaData_Filer 1
(SWI &482C8)
Checks whether an object leafname contains invalid characters
On entry
R0 = 1
R1 = pointer to object leafname (control or space terminated)
On exit
R0 = if Z set on exit, length of leafname, else corrupted
R1 preserved
Z set if object leafname does not contain invalid characters
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This routine is used by AddressDevice DA to determine if a discname contains invalid characters. Invalid characters are:
$&%@\^:.#*"|
KaData_Filer 2
(SWI &482C8)
Finds the next element of a pathname
On entry
R0 = 2
R1 = pointer to partial pathname
On exit
R0 preserved
R1 = pointer to partial pathname, with the first element skipped
Z set if pathname complete (in which case R1 points after null)
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This routine is used by AddressDevice DA to read successive pathname elements.
KaData_FillBytes
(SWI &482C9)
Fill a block of memory with a specified byte or word value
On entry
R1 = byte to fill with (or if R1 > 255, special word designator)
R2 = destination address
R3 = length
On exit
R0-R3 corrupted
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This is a fast memory initialization routine, internally similar to KaData_MoveBytes (SWI &482C0). It initializes any number of bytes (>0) at the destination address.
If R1 < 256 on entry, the memory is filled with bytes having the value of R1. If R1 > 255 on entry, the memory is filled with words having the value of -x, where x is R1 rotated left by 16 bits. This allows fills to use word values from 0 to 2 147 483 647, and negative values from -65 536 to -1.
If, when filling with words, the initial address is not word aligned, the low byte of x is used to pad to the next word boundary. Similar padding is carried out at the end of the initialized memory if it does not finish on a word boundary.
Related SWIs
KaData_MoveBytes (SWI &482C0)
Related vectors
None
KaData_ReadInteger
(SWI &482CA)
Not yet implemented
KaData_WriteInteger
(SWI &482CB)
Not yet implemented
KaData_CountBytes
(SWI &482CC)
Do an indexed search for a particular byte value (bi-directional)
On entry
R0 = byte value to count
R1 = start address
R2 = maximum number to count
R3 = length of block to be searched (negative to search backwards)
On exit
R0 = address of last match (-1 if no matches found)
R1 = address of byte where search would resume
R2 = number left to count
R3 = number of unexamined bytes (negative if searching backwards)
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This routine can be used to skip to terminators or delimiters in a block of bytes.
KaData_GetEntryPoints
(SWI &482CD)
Provides addresses of SWI handler routines and related support
On entry
R0 = SWI offset (or negative for special reason code)
R1 = address of buffer to store 65 addresses (if R0=-1 on entry)
On exit
R0 preserved
R1 = address beyond end of buffer (if R0=-1 on entry, preserved otherwise)
R2 = address of given SWI handler (or maximum SWI offset if R0=-1 on entry)
Interrupts
Interrupt status is not altered
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
The meaning of this call depends on the value of R0 as follows:
R0 Meaning
0-63 Return address of specific SWI handler in R2 (for SWI offset in R0)
-1 Return address of all handlers in buffer pointed to by R1
-2 Return address of main SWI handler in R2
-3 Anchor module
-4 Release module
When you specify R0 = -1, the layout of the buffer is:
Offset Meaning
0 Address of main SWI handler (SWI chunk &482C0)
4 Address of handler for KaData_MoveBytes (SWI offset 0)
:
256 Address of handler for KaData_Undefined63 (SWI offset 63)
In this instance, R2 returns the highest defined SWI offset in the chunk.
If you specify R0 > 0 on entry, but there is no handler for that SWI offset, then R2 will contain 0 on exit.
All addresses returned are absolute, but depend on the current address of the KaData module in the RMA address space. In order to use them, you should first call this routine with R0 = -3 to anchor the module in the RMA. When you have finished using the entry points, be sure to use R0 = -4 to release it. Ideally, you should not anchor the module for long periods of time in a multitasking environment.
The following entry points require R12 be set-up to point to the KaData module's private word, and must be called in Supervisor mode:
KaData_MetronomicTimerOn (SWI &482D2)
KaData_MetronomicTimerOff (SWI &482D3)
KaData_MetronomicTimerSmash (SWI &482D4)
KaData_ReadMetronomicTimer (SWI &482D5)
For any other entry point returned by this routine:
On entry: Entry registers as for SWI
R13 must be a full descending stack with 512 bytes free
R11, R12, R14 may contain any value (unless stated o/w)
Processor is in a 26-bit PC mode
Interrupt status is undefined
On exit: Exit registers (and flags) as for SWI
R10-R12 may be corrupted
Processor mode is unchanged
Interrupt status is unaltered
Re-entrancy: Check SWI documentation for re-entrancy
Note that KaData_MoveBytes (SWI &482C0) is an APCS compliant entry point. All others are not, and will require wrapping code to be called as an APCS compliant entry point. A wrapper would move R1 to R0, R2 to R1, etc., preserve the necessary registers, make the call, and do the inverse on exit.
Related SWIs
None
Related vectors
None
Related variables
KaData$ModuleAnchor
KaData_CallSupervisor32
(SWI &482CE)
Calls a routine in ARM Supervisor32 mode (not implemented in 0.51)
On entry
R0-R7 as required for routine
R8 = address of routine to call
R9 = R12 value for entry to routine
R10,R11 as required for routine (R11 applicable only if called directly)
R12 = KaData module instantiation private word pointer (if called directly)
R13 = supervisor stack pointer (if called directly)
R14 = flags and 26-bit PC return value for call (if called directly)
On exit
R0-R10 and flags as returned by routine
R11-R13 as returned by routine (if called directly)
Interrupts
Interrupts are disabled
Fast interrupts are disabled temporarily (before entry to the routine)
Processor mode
Processor is in SVC26 mode on entry and exit
Routine is executed in SVC32 mode, with KaData SVC32 SWI handler enabled
Re-entrancy
SWI is not re-entrant
Use
This call is for RISC OS 3.50 and above only.
This SWI can be used to call routines which:
- lie outside 26-bit address space
- end up calling routines which are outside 26-bit address space
The entry process involves:
- claiming processor SWI vector, or, if a different approach is
suggested by a call to KaData_ChangeProcessorVector32 (SWI &482CF),
this will be followed instead.
- forcing ARM to enter Supervisor32 mode
- saving KaData R12 on the stack and loading R12 with R9
- calling the routine
The exit process involves:
- saving routine exit R12 and retrieving KaData R12
- releasing processor SWI vector, or, if a different approach is
suggested by a call to KaData_ChangeProcessorVector32 (SWI &482CF),
this will be followed instead.
- forcing ARM to enter Supervisor26 mode
- retrieving routine exit R12
If the default entry and exit actions have not been overridden by KaData_ChangeProcessorVector32, the replaced SWI vector performs as follows:
- The KaData SWI claimant needs to patch to the OS SWI handler with a
routine that can work around the clipping of R14_svc which the OS
SWI handler performs to retrieve the SWI instruction. (This forces
R14_svc into 26-bit space, which can yield an incorrect instruction
and an incorrect return address.) To be able to do this, the routine
needs to fake a SWI call in 26-bit space. This is done, in broad
This call is intended for changing the entry and exit sequence followed by KaData_CallSupervisor32 (SWI &482CE). The normal action of such routines is to replace and subsequently restore the processor vectors to facilitate running in SVC32 mode.
R0 should be set to the address of your vector claim routine, which is entered in SVC26 mode. R1 should be set to the address of your vector release routine, which is entered in SVC32 mode. If you set R0 = 0 on entry, the default actions will be restored.
If you claim a processor vector within your vector claim routine, the handlers you set up will be called during the execution of a SVC32 routine running under KaData_CallSupervisor32 (SWI &482CE). This means:
- Handlers which set themselves up within your routine are called
"KaData claimants". These claimants will be called from a parent
environment that is in Supervisor32 mode, unless your routine is
presently threaded more than once.
- Routines which set themselves up with the operating system, and are
the owners of the vectors when KaData_CallSupervisor32 is entered,
are called "actual claimants". These claimants are usually defined
to execute in 26-bit processor modes as follows:
Number Vector name (default claimant; 26-bit processor mode)
2 SWI (operating system software interrupt handler; SVC)
3 Prefetch abort (abort on instruction fetch error; SVC)
4 Data abort (abort on data transfer error; SVC)
5 Reserved (address exception error)
6 IRQ (operating system interrupt handler; IRQ)
7 FIQ (current FIQ claimant; FIQ)
So, the purpose of your vector claim routine is to replace actual claimants with your KaData claimants. And the purpose of your vector release routine is to restore the actual claimants. Usually KaData claimants need to access the actual claimants, and merely perform pre and post processing on the vectors to ensure the desired actions be taken for code running in Supervisor32 mode.
This call pokes TabModule fields to simulate the behaviour of the actual
module (which is stored in 32-bit space) as follows:
- It will disable the start field for actual modules with a zero in
this field.
- It will disable the service call field for modules with a zero in
this field.
- It will adjust the offset in the title field so that it points to
title string in the actual module.
- It will adjust the offset in the help field so that it points to
title string in the actual module.
- It will adjust the offset in the keywords field so that it points to
keyword table in the actual module.
- It will disable the SWI handler field for modules with a zero in
this field.
- It will adjust the offset in the SWI table field so that it points to
SWI table in the actual module.
- It will disable the SWI decoder field for modules with a zero in
this field.
- The TabModule is poked with the location of the KaData_OSModule SWI
decoder (not used in AddressDevice 2.00 prototype).
The routine then calls the initialization routine of the actual module (where present), in SVC32 mode. KaData is anchored in RMA, if it is not already.
KaData_OSModule 129
(SWI &482D0)
Finalizes a module in 32-bit space
On entry
R0 = 129
R2 = TabModule address
R6 = actual module header address
R9 = pointer to module private word
On exit
Undefined
Use
This routine calls the finalization routine of the actual module (where present), in SVC32 mode. KaData is deanchored provided it isn't anchored by another part of the system (e.g. another SVC32 module).
KaData_OSModule 130
(SWI &482D0)
Starts executing a module in 32-bit space
On entry
R0 = 130
R1 = actual module header address
R9 = pointer to module private word
On exit
R0 = pointer to error block
V set
Use
This routine cannot reasonably be implemented at this time, so it returns an error.
KaData_OSModule 131
(SWI &482D0)
Invokes the service call handler code of a module in 32-bit space
On entry
R0 = 131
R8 = actual module header address
R9 = pointer to module private word
On exit
Undefined
Use
Enters SVC32 mode, and calls the actual module code.
KaData_OSModule 132
(SWI &482D0)
Invokes the SWI handler code of a module in 32-bit space
On entry
R0 = 132
R8 = actual module header address
R9 = pointer to module private word
On exit
Undefined
Use
Enters SVC32 mode, and calls the actual module code.
KaData_OSModule 133
(SWI &482D0)
Invokes the SWI decoder code of a module in 32-bit space
On entry
R0 = 133
R8 = actual module header address
R9 = pointer to module private word
On exit
Undefined
Use
Enters SVC32 mode, and calls the actual module code.
KaData_Assemble
(SWI &482D1)
Assembles an ARM instruction
On entry
R0 = execution address of instruction
R1 = pointer to word to contain assembled instruction
R2 = base instruction code
R3 = condition code
other registers depend on base instruction code
On exit
-
Interrupts
Interrupt status is not defined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use
This general purpose SWI assembles an ARM instruction from data specified by the entry registers, and stores it at the address specified.
The following table lists the condition codes:
Condition Code
AL &E
CC &3
CS &2
EQ &0
GE &A
GT &C
HI &8
HS &2
LE &D
LO &3
LS &9
LT &B
MI &4
PL &5
NE &1
NV &F
VC &7
VS &6
The following table is a summary of base instruction codes and the entry register values required:
Instruction Code R4 R5 R6 R7
ABS &F2 FPR FD 0 FS1
ABS &F20 FPR FD 0 FC
ACS &FC FPR FD 0 FS1
ACS &FC0 FPR FD 0 FC
ADC &0A D S1 S2 Shift
ADC &2A D S1 Const -
ADCS &0B D S1 S2 Shift
ADCS &2B D S1 Const -
ADD &08 D S1 S2 Shift
ADD &28 D S1 Const -
ADDS &09 D S1 S2 Shift
ADDS &29 D S1 Const -
ADF &E0 FPR FD FS1 FS2
ADF &E00 FPR FD FS1 FC
AND &00 D S1 S2 Shift
AND &20 D S1 Const -
ANDS &01 D S1 S2 Shift
ANDS &21 D S1 Const -
ASN &FB FPR FD 0 FS1
ASN &FB0 FPR FD 0 FC
ATN &FD FPR FD 0 FS1
ATN &FD0 FPR FD 0 FC
B &A0 Addr - - -
BL &B0 Addr - - -
BIC &1C D S1 S2 Shift
BIC &3C D S1 Const -
BICS &1D D S1 S2 Shift
BICS &3D D S1 Const -
CMF &A8 FPR 7 FS1 FS2
CMF &A80 FPR 7 FS1 FC
CMFE &AA FPR 7 FS1 FS2
CMFE &AA0 FPR 7 FS1 FC
CMN &17 0 S1 S2 Shift
CMN &37 0 S1 Const -
CMNP &17 15 S1 S2 Shift
CMNP &37 15 S1 Const -
CMP &15 0 S1 S2 Shift
CMP &35 0 S1 Const -
CMPP &15 15 S1 S2 Shift
CMPP &35 15 S1 Const -
CNF &A9 FPR 7 FS1 FS2
CNF &A90 FPR 7 FS1 FC
CNFE &AB FPR 7 FS1 FS2
CNFE &AB0 FPR 7 FS1 FC
COS &F9 FPR FD 0 FS1
COS &F90 FPR FD 0 FC
DVF &E4 FPR FD FS1 FS2
DVF &E40 FPR FD FS1 FC
EOR &02 D S1 S2 Shift
EOR &22 D S1 Const -
EORS &03 D S1 S2 Shift
EORS &23 D S1 Const -
EXP &F7 FPR FD 0 FS1
EXP &F70 FPR FD 0 FC
FML &E9 FPR FD FS1 FS2
FML &E90 FPR FD FS1 FC
FDV &EA FPR FD FS1 FS2
FDV &EA0 FPR FD FS1 FC
FIX &A10 FPR FS1 D -
FLT &A00 FPR FD S1 -
FRD &EB FPR FD FS1 FS2
FRD &EB0 FPR FD FS1 FC
LDF (DA) &C1 FPR FR A1 Offset
LDF (IA) &C9 FPR FR A1 Offset
LDF (DB) &D1 FPR FR A1 Offset
LDF (DB!) &D3 FPR FR A1 Offset
LDF (IB) &D9 FPR FR A1 Offset
LDF (IB!) &DB FPR FR A1 Offset
LDMDA &81 A1 L - -
LDMDA (!) &83 A1 L - -
LDMDA (^) &85 A1 L - -
LDMDA (!^) &87 A1 L - -
LDMDB &91 A1 L - -
LDMDB (!) &93 A1 L - -
LDMDB (^) &95 A1 L - -
LDMDB (!^) &97 A1 L - -
LDMEA is equivalent to LDMDB
LDMED is equivalent to LDMIB
LDMFA is equivalent to LDMDA
LDMFD is equivalent to LDMIA
LDMIA &89 A1 L - -
LDMIA (!) &8B A1 L - -
LDMIA (^) &8D A1 L - -
LDMIA (!^) &8F A1 L - -
LDMIB &99 A1 L - -
LDMIB (!) &9B A1 L - -
LDMIB (^) &9D A1 L - -
LDMIB (!^) &9F A1 L - -
LDR &59 R 15 Addr -
LDR (DA) &41 R A1 Offset -
LDR (DA) &61 R A1 A2 Shift
LDR (DB) &51 R A1 Offset -
LDR (DB) &71 R A1 A2 Shift
LDR (IA) &49 R A1 Offset -
LDR (IA) &69 R A1 A2 Shift
LDR (IB) &59 R A1 Offset -
LDR (IB) &79 R A1 A2 Shift
LDR (DB!) &53 R A1 Offset -
LDR (DB!) &73 R A1 A2 Shift
LDR (IB!) &5B R A1 Offset -
LDR (IB!) &7B R A1 A2 Shift
LDRB (DA) &45 R A1 Offset -
LDRB (DA) &65 R A1 A2 Shift
LDRB (DB) &55 R A1 Offset -
LDRB (DB) &75 R A1 A2 Shift
LDRB (IA) &4D R A1 Offset -
LDRB (IA) &6D R A1 A2 Shift
LDRB (IB) &5D R A1 Offset -
LDRB (IB) &7D R A1 A2 Shift
LDRB (DB!) &57 R A1 Offset -
LDRB (DB!) &77 R A1 A2 Shift
LDRB (IB!) &5F R A1 Offset -
LDRB (IB!) &7F R A1 A2 Shift
LDRBT (DA) &47 R A1 Offset -
LDRBT (DA) &67 R A1 A2 Shift
LDRBT (IA) &4F R A1 Offset -
LDRBT (IA) &6F R A1 A2 Shift
LDRT (DA) &43 R A1 Offset -
LDRT (DA) &63 R A1 A2 Shift
LDRT (IA) &4B R A1 Offset -
LDRT (IA) &6B R A1 A2 Shift
LGN &F6 FPR FD 0 FS1
LGN &F60 FPR FD 0 FC
LOG &F5 FPR FD 0 FS1
LOG &F50 FPR FD 0 FC
MLA &30 D S1 S2 S3
MNF &F1 FPR FD 0 FS1
MNF &F10 FPR FD 0 FC
MOV &15 D 0 S1 Shift
MOV &35 D 0 Const -
MUF &E1 FPR FD FS1 FS2
MUF &E10 FPR FD FS1 FC
MUL &10 D S1 S2 0
MVF &F0 FPR FD 0 FS1
MVF &F00 FPR FD 0 FC
MVN &17 D 0 S1 Shift
MVN &37 D 0 Const -
ORR &18 D S1 S2 Shift
ORR &38 D S1 Const -
ORRS &19 D S1 S2 Shift
ORRS &39 D S1 Const -
POL &EC FPR FD FS1 FS2
POL &EC0 FPR FD FS1 FC
POW &E6 FPR FD FS1 FS2
POW &E60 FPR FD FS1 FC
RDF &E5 FPR FD FS1 FS2
RDF &E50 FPR FD FS1 FC
RFC &A50 0 0 D -
RFS &A30 0 0 D -
RMF &E8 FPR FD FS1 FS2
RMF &E80 FPR FD FS1 FC
RND &F3 FPR FD 0 FS1
RND &F30 FPR FD 0 FC
RPW &E7 FPR FD FS1 FS2
RPW &E70 FPR FD FS1 FC
RSB &06 D S1 S2 Shift
RSB &26 D S1 Const -
RSBS &07 D S1 S2 Shift
RSBS &27 D S1 Const -
RSC &0E D S1 S2 Shift
RSC &2E D S1 Const -
RSCS &0F D S1 S2 Shift
RSCS &2F D S1 Const -
RSF &E3 FPR FD FS1 FS2
RSF &E30 FPR FD FS1 FC
SBC &0C D S1 S2 Shift
SBC &2C D S1 Const -
SBCS &0D D S1 S2 Shift
SBCS &2D D S1 Const -
SIN &F8 FPR FD 0 FS1
SIN &F80 FPR FD 0 FC
SQT &F4 FPR FD 0 FS1
SQT &F40 FPR FD 0 FC
STF (DA) &C0 FPR FR A1 Offset
STF (IA) &C8 FPR FR A1 Offset
STF (DB) &D0 FPR FR A1 Offset
STF (DB!) &D2 FPR FR A1 Offset
STF (IB) &D8 FPR FR A1 Offset
STF (IB!) &DA FPR FR A1 Offset
STMDA &80 A1 L - -
STMDA (!) &82 A1 L - -
STMDA (^) &84 A1 L - -
STMDA (!^) &86 A1 L - -
STMDB &90 A1 L - -
STMDB (!) &92 A1 L - -
STMDB (^) &94 A1 L - -
STMDB (!^) &96 A1 L - -
STMEA is equivalent to STMIA
STMED is equivalent to STMDA
STMFA is equivalent to STMIB
STMFD is equivalent to STMDB
STMIA &88 A1 L - -
STMIA (!) &8A A1 L - -
STMIA (^) &8C A1 L - -
STMIA (!^) &8E A1 L - -
STMIB &98 A1 L - -
STMIB (!) &9A A1 L - -
STMIB (^) &9C A1 L - -
STMIB (!^) &9E A1 L - -
STR &58 R 15 Addr -
STR (DA) &40 R A1 Offset -
STR (DA) &60 R A1 A2 Shift
STR (DB) &50 R A1 Offset -
STR (DB) &70 R A1 A2 Shift
STR (IA) &48 R A1 Offset -
STR (IA) &68 R A1 A2 Shift
STR (IB) &58 R A1 Offset -
STR (IB) &78 R A1 A2 Shift
STR (DB!) &52 R A1 Offset -
STR (DB!) &72 R A1 A2 Shift
STR (IB!) &5A R A1 Offset -
STR (IB!) &7A R A1 A2 Shift
STRB (DA) &44 R A1 Offset -
STRB (DA) &64 R A1 A2 Shift
STRB (DB) &54 R A1 Offset -
STRB (DB) &74 R A1 A2 Shift
STRB (IA) &4C R A1 Offset -
STRB (IA) &6C R A1 A2 Shift
STRB (IB) &5C R A1 Offset -
STRB (IB) &7C R A1 A2 Shift
STRB (DB!) &56 R A1 Offset -
STRB (DB!) &76 R A1 A2 Shift
STRB (IB!) &5E R A1 Offset -
STRB (IB!) &7E R A1 A2 Shift
STRBT (DA) &46 R A1 Offset -
STRBT (DA) &66 R A1 A2 Shift
STRBT (IA) &4E R A1 Offset -
STRBT (IA) &6E R A1 A2 Shift
STRT (DA) &42 R A1 Offset -
STRT (DA) &62 R A1 A2 Shift
STRT (IA) &4A R A1 Offset -
STRT (IA) &6A R A1 A2 Shift
SUB &04 D S1 S2 Shift
SUB &24 D S1 Const -
SUBS &05 D S1 S2 Shift
SUBS &25 D S1 Const -
SUF &E2 FPR FD FS1 FS2
SUF &E20 FPR FD FS1 FC
SWI &F0 -1 SID - -
TAN &FA FPR FD 0 FS1
TAN &FA0 FPR FD 0 FC
TEQ &11 0 S1 S2 Shift
TEQ &31 0 S1 Const -
TEQP &11 15 S1 S2 Shift
TEQP &31 15 S1 Const -
TST &13 0 S1 S2 Shift
TST &33 0 S1 Const -
TSTP &13 15 S1 S2 Shift
TSTP &33 15 S1 Const -
WFC &A40 0 0 S1 -
WFS &A20 0 0 S1 -
Each of the mnemonics used to indicate register contents in the above table are described below:
Mnemonic Meaning Entry register contents
A1 ARM register: first address Cardinal, in the range 0-15
A2 ARM register: second address Cardinal, in the range 0-15
Addr ARM memory address 26-bit cardinal
Const Immediate constant 32-bit cardinal
D ARM register: destination Cardinal, in the range 0-15
FC FP immediate constant The constant is specified by
a code in the range 0-7. The
following table gives a list
of valid FP constants:
Code FP constant
0 0.0
1 1.0
2 2.0
3 3.0
4 4.0
5 5.0
6 0.5
7 10.0
FD FP register: destination Cardinal, in the range 0-7
FPR FP precision and rounding This value specifies the FP
precision and rounding, as
follows:
Value Instruction suffix
0 S
1 SP
2 SM
3 SZ
4 D
5 DP
6 DM
7 DZ
8 E
9 EP
10 EM
11 EZ
12 P
13 PP
14 PM
15 PZ
FR FP register Cardinal, in the range 0-7
FS1 FP register: first source Cardinal, in the range 0-7
FS2 FP register: second source Cardinal, in the range 0-7
L ARM register list 16-bit bitmap (register
included if bit set)
e.g. R0 included if bit 0 is
set, R15 included if bit 15
is set
Offset Memory address offset For all instructions apart
from LDRB and STRB, the
offset must be a multiple of
4. For LDR, STR, LDM and
STM, the offset must be in
the range 0-4095. For LDF
and STF, the offset must be
in the range 0-4080.
R ARM register Cardinal, in the range 0-15
S1 ARM register: first source Cardinal, in the range 0-15
S2 ARM register: second source Cardinal, in the range 0-15
Shift Register shift/rotate operation Bits 0-2 are the subinst-
ruction code. If bit 0 is
set, then bits 3-7 are shift
factor. If bit 0 is unset,
then bits 4-7 specify the
ARM register containing the
shift factor, and bit 7 is
unset. The subinstruction
codes are listed below:
Code Shift/rotate subinstruction
0 LSL #<factor>
ASL #<factor>
1 LSL <register>
ASL <register>
2 LSR #<factor>
3 LSR <register>
4 ASR #<factor>
5 ASR <register>
6 RRX (<factor> = 0)
6 ROR #<factor> (<factor> > 0)
7 ROR <register>
SID SWI identification number 26-bit cardinal
Note that is the caller's responsibility to ensure that the data passed meets the requirements specified above. For example, no error will be returned if an attempt is made to assemble an instruction which refers to R16. If the caller does not meet the requirements, then the instruction which is assembled will almost certainly perform the wrong task, if it executes at all.
If an immediate constant cannot be encoded, then the error Invalid immediate constant will be generated. Similarly, if an address cannot be successfully converted to a PC-relative offset, then the error Invalid address: translation to offset failed will be returned.
Related SWIs
Debugger_Disassemble (SWI &40380)
Related vectors
None
KaData_MetronomicTimerOn
(SWI &482D2)
Start a timer using IOC Timer 1
On entry
-
On exit
-
Interrupts
Interrupts are disabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is not re-entrant
Use
This SWI starts KaData's metronomic timer. If it is already in use, the usage count is incremented.
If the ticker is not in use at the time of this call, the increment quantum is set to 1000, which gives a millisecond timer.
Timer 1 can be more reliable than Timer 0, even with a high quantum. A low quantum is more accurate because a lost tick has less effect, and even a high quantum can be less susceptible to drift on some machines (like Kasoft Central).
Starting the metronomic timer will cause any previous claimants of the Timer 1 interrupt to stop being called, so beware.
Related SWIs
KaData_MetronomicTimerOff (SWI &482D3),
KaData_MetronomicTimerSmash (SWI &482D4),
KaData_ReadMetronomicTimer (SWI &482D5),
KaData_SetMetronomicTimerQuantum (SWI &482DE)
Related vectors
None
KaData_MetronomicTimerOff
(SWI &482D3)
Finish using the timer based on IOC Timer 1
On entry
-
On exit
-
Interrupts
Interrupts are disabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is not re-entrant
Use
This SWI should be called to finish using KaData's metronomic timer. If it is in use by another program, the usage count is decremented. Otherwise, the Timer 1 interrupt will be disabled and the metronomic timer will stop.
Related SWIs
KaData_MetronomicTimerOn (SWI &482D2),
KaData_MetronomicTimerSmash (SWI &482D4),
KaData_ReadMetronomicTimer (SWI &482D5),
KaData_SetMetronomicTimerQuantum (SWI &482DE)
Related vectors
None
KaData_MetronomicTimerSmash
(SWI &482D4)
Kill the timer based on IOC Timer 1
On entry
-
On exit
-
Interrupts
Interrupts are disabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is not re-entrant
Use
This SWI can be called to reset the usage count on the KaData metronomic timer to zero, disabling the Timer 1 interrupt and stopping the metronomic timer. For use in emergencies only, as some programs may be relying on the timer.
Related SWIs
KaData_MetronomicTimerOn (SWI &482D2),
KaData_MetronomicTimerOff (SWI &482D3),
KaData_ReadMetronomicTimer (SWI &482D5),
KaData_SetMetronomicTimerQuantum (SWI &482DE)
Related vectors
None
KaData_ReadMetronomicTimer
(SWI &482D5)
Read the timer based on IOC Timer 1
On entry
-
On exit
R0 = low 32-bits of timer
R1 = high 32-bits of timer
Interrupts
Interrupts are disabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is re-entrant
Use
This SWI should be called to read the value of KaData's metronomic timer.
The timer is a 64-bit value which is the number of microseconds (1 x 10 ^ -6 s) the timer has been running since the KaData module was last initialized. The accuracy is affected by the quantum currently set by KaData_SetMetronomicTimerQuantum (SWI &482DE).
Wraparound will no longer occur in normal use, and it is no longer necessary to deal with this contingency.
Related SWIs
KaData_MetronomicTimerOn (SWI &482D2),
KaData_MetronomicTimerOff (SWI &482D3),
KaData_MetronomicTimerSmash (SWI &482D4),
KaData_SetMetronomicTimerQuantum (SWI &482DE)
Related vectors
None
KaData_PokeDynamicArea
(SWI &482D6)
Changes the maximum size of a dynamic area (not implemented in 0.51)
On entry
R1 = area number
R5 = new maximum size for area, in bytes
On exit
R1,R5 preserved
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call is for RISC OS 3.50 and above only.
This SWI will reprogram the maximum size of an existing dynamic area. Do not attempt to set a maximum which causes the area, at its current position, to overlap another. Do not attempt to set a maximum which exceeds the total available memory on the system. Do not set a maximum which is below the current size of the area.
KaData_ObmatOp
(SWI &482D7)
Perform an operation on an object matrix, or Obmat for short
(not implemented in 0.51)
On entry
R0 = reason code
other registers are parameters and depend upon the reason code
On exit
R0 preserved
other registers depend on the reason code
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This SWI provides a number of calls to manipulate Obmats.
R0 Action
0 Verify file integrity
Related SWIs
None
Related vectors
None
KaData_MatchWild
(SWI &482D8)
Compares a wildcarded string against another string
On entry
R0 = pointer to first (wildcarded) string (usu. null terminated)
R1 = pointer to second (unwildcarded) string (null terminated)
R2 = single (one) character wildcard
R3 = multiple (zero or more) character wildcard
R4 = alternative terminator character (e.g. '.' for a pathname element)
R5 = flags or pointer to lower case table (R5 > 3)
Bit Meaning
0 Ignore case
1 Ignore accents
2-31 Reserved (must be 0)
R6 = when R5 > 3, pointer to plain table (or 0 if not used)
On exit
R0-R6 preserved
Z set if strings match
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is re-entrant
Use
This SWI uses the wildcards given in the first string together with character mappings defined by the current territory to determine if the second string matches. It is particularly useful for filing systems.
If the TerritoryManager module is not present, you must provide the 256 byte character translation tables yourself by setting R5 and R6 to point to the required tables. R6 may be 0 if only one mapping is needed.
KaData_CopyString
(SWI &482D9)
Copies a control-terminated string into a buffer
On entry
R0 = pointer to source string (usu. control terminated)
R1 = pointer to buffer to hold copied string
R2 = alternative terminator character
On exit
-
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is re-entrant
Use
Copies a control character (ASCII 0-31) terminated string into the specified buffer, replacing the terminator with a null. This call should only be made for strings whose maximum possible length is known, so that the buffer can be made big enough. An alternative terminator may be given- this will be replaced by a null character in the resulting buffer.
Related SWIs
None
Related vectors
None
KaData_Heap
(SWI &482DA)
Support for shifting heaps (not implemented in 0.51)
On entry
R0 = reason code
other registers are parameters and depend upon the reason code
On exit
R0 preserved
other registers depend on the reason code
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This SWI provides a number of calls which provide support for shifting heaps.
R0 Action
0 Initialize heap
1 New dynamic area based heap (RISC OS 3.50 and above only)
2 Remove dynamic area based heap (RISC OS 3.50 and above only)
3 New shifting block
4 New static block
5 Get block details
6 Change block details
7 Remove block
8 Remove all blocks with ID given
9 Change details of all blocks with ID given
10 Resize block
11 Extend block given offset
12 New anchor
13 Remove anchor
14 Reduce size of heap
15 Fully compact heap
16 Get heap details
17 Change heap details
18 New relocation stack
19 Get relocation stack details
20 Change relocation stack details
21 Push onto relocation stack
22 Pull off relocation stack
23 Remove relocation stack
24 Enumerate blocks
Related SWIs
OS_Heap (SWI &1D)
Related vectors
None
KaData_Module
(SWI &482DB)
Support for KaData resource module files
On entry
R0 = reason code
other registers are parameters and depend upon the reason code
On exit
R0 preserved
other registers depend on the reason code
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This SWI provides a number of calls to deal with KaData resource module files. These files have type KaDatMod (&3E5).
R0 Action
0 Build menu tree from ROMD (RISC OS Menu Data) file
1 Build menu from KDOS (KaData Ordinal String) file
This call reads the file sequentially, which means that it can be used to read a resource module file from a filing system like Acorn PipeFS.
Related SWIs
None
Related vectors
None
KaData_Module 0
(SWI &482DB)
Build menu tree from ROMD (RISC OS Menu Data) file
On entry
R0 = 0
R1 = pointer to filename
R2 = pointer to block to store data (-1 to allocate a block from the RMA)
On exit
R0,R1 preserved
R2 = pointer to menu block
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
Takes a menu data file, consisting of a menu block where all addresses are offsets within the file (excluding the four byte header, so that offset 0 is actually offset 4), and builds a menu block that may be passed to Wimp_CreateMenu (SWI &400D4). Further menu blocks may also be incorporated to define submenus. The word after the last menu block should be set to -1. Indirected icon data should follow the last menu block.
A menu data file may be conveniently created by an assembler.
This call reads the file sequentially, which means that it can be used to read a resource module file from a filing system like Acorn PipeFS.
KaData_Module 1
(SWI &482DB)
Build menu from KDOS (KaData Ordinal String) file
On entry
R0 = 1
R1 = pointer to filename
R2 = pointer to block to store menu (-1 to allocate a block from the RMA)
R3 = pointer to block to store indirected icons (-1 to allocate a block)
R4 = menu item flags
R5 = submenu pointer (-1 for leaf items)
On exit
R0,R1 preserved
R2 = pointer to menu block
R3 = pointer to indirected icon block
R4,R5 preserved
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
Takes a KaData Ordinal String file, and builds a menu from it, which may be passed to Wimp_CreateMenu (SWI &400D4).
This call reads the file sequentially, which means that it can be used to read a resource module file from a filing system like Acorn PipeFS. This feature is used by the AddressDevice DA Filer to build a menu from the spooled output of *Discs.
KaData_GetString
(SWI &482DC)
Reads a string of characters from a file
On entry
R0 = preferred terminator character and flags
R1 = file handle
R2 = buffer for string
R3 = buffer size
R4 = sequential pointer (ignored when not required by flags)
On exit
R0 = terminator character encountered in file
R1 preserved
R2 = pointer to terminator character in buffer
R3 = space remaining in buffer
R4 = new sequential pointer (preserved when not required by flags)
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is re-entrant
Use
Reads an arbitarily terminated string from a file, using register bindings similar to OS_GBPB.
R4 specifies how the string is read, as follows:
Bits Meaning
0-7 Terminator character
8 Set if string can be terminated by any control character
9 Set to read from current sequential pointer (don't use R4 on entry)
10 Set to find new sequential pointer (use R4 on exit when bit 9 set)
Note that bit 10 only applies if bit 9 is set. That is, a read from a designated pointer (bit 9 unset) will always return an updated pointer in R4 on exit, but a read from the current sequential pointer (bit 9 set) will only use R4 on exit if bit 10 is set.
R4 = sequential pointer (ignored when not required by flags)
On exit
R0 = terminator character written to file
R1 preserved
R2 = pointer to terminator character in buffer
R3 = number of bytes written to file
R4 = new sequential pointer (preserved when not required by flags)
Interrupts
Interrupt status is undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is re-entrant
Use
Reads a pre-terminated or control character terminated string from a buffer, and places it in a file with the specified terminator, using register bindings similar to OS_GBPB.
R4 specifies how the string is written, as follows:
Bits Meaning
0-7 Terminator character (will replace control character if bit 8 set)
8 Set if buffered string can be terminated by any control character
9 Set to write to current sequential pointer (don't use R4 on entry)
10 Set to find new sequential pointer (use R4 on exit when bit 9 set)
Note that bit 10 only applies if bit 9 is set. That is, a write to a designated pointer (bit 9 unset) will always return an updated pointer in R4 on exit, but a write to the current sequential pointer (bit 9 set) will only use R4 on exit if bit 10 is set.
Set the quantum used by the timer based on IOC Timer 1
On entry
R0 = new quantum (or 0 to read)
R1 = 0 to write, -1 to read
On exit
R0 = old quantum
R1 preserved
Interrupts
Interrupts are disabled
Processor mode
Processor is in SVC mode
Re-entrancy
Routine is not re-entrant
Use
This SWI will set the increment quantum of KaData's metronomic timer.
Valid quantum values are:
1 Timer is updated at 1 MHz (will stall some machines)
10 Timer is updated at 100 kHz (will severely slow machines)
100 Timer is updated at 10 kHz
1000 Timer is updated at 1 kHz (default)
10000 Timer is updated at 100 Hz
You should always check the quantum value before changing it. Normally it is acceptable to reduce the quantum, but increasing the quantum should be avoided unless you are sure that you are the only client of the timer.
